数据库界的Swagger：一键生成数据库文档！你不了解一下？

程序猿DD 2021-11-13

The following article is from 芋道源码 Author 老艿艿

对于API的文档，我们有Swagger等工具来自动生成了。但有有一类文档还是常常困扰着我们，那就是数据库表结构的文档。相信很多同学都有过手写数据库表结构文档 的经历吧？常规操作就是一通无脑的 CV 大法，产出一份小几十页的 Word 文档。

那么，是否有什么工具，可以帮我们偷懒高效的自动生成数据库表结构文档呢？

还真有！下面就来介绍这样一个工具：screw！

2. screw 简介

screw 是一个简洁好用的数据库表结构文档的生成工具 ，支持 MySQL、Oracle、PostgreSQL 等主流的关系数据库。

screw 的仓库地址是 https://github.com/pingfangushi/screw，感兴趣的胖友，可以研究一波。

生成的文档有 HTML、Word、Markdown 三种格式，示例如下图所示：

格式	图
HTML
Word
Markdown

如果您正在学习Spring Boot，推荐一个连载多年还在继续更新的免费教程：http://blog.didispace.com/spring-boot-learning-2x/

3. 快速入门

screw 有两种方式来生成文档，通过 Java 代码 或者 Maven 插件 。

下面，我们来分别快速入门下。

3.1 使用 Java 代码的方式

创建 lab-70-db-doc-screw-01 示例项目，使用 screw 的 Java 代码 的方式，生成文档。

示例示例

3.1.1 引入依赖

在 pom.xml 文件中，引入 screw 的依赖 screw-core。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-01</artifactId>

    <dependencies>
        <!-- screw 库，简洁好用的数据库表结构文档生成器 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>

        <!-- 数据库连接 -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.22</version>
        </dependency>
    </dependencies>

</project>

依赖 HikariCP 和 mysql-connector-java 是为了连接 MySQL 数据库。

3.1.2 ScrewMain

创建 ScrewMain 类，使用 screw 生成文档。代码如下：

public class ScrewMain {

    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";

    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final EngineFileType FILE_OUTPUT_TYPE = EngineFileType.HTML; // 可以设置 Word 或者 Markdown 格式
    private static final String DOC_FILE_NAME = "数据库文档";
    private static final String DOC_VERSION = "1.0.0";
    private static final String DOC_DESCRIPTION = "文档描述";

    public static void main(String[] args) {
        // 创建 screw 的配置
        Configuration config = Configuration.builder()
                .version(DOC_VERSION)  // 版本
                .description(DOC_DESCRIPTION) // 描述
                .dataSource(buildDataSource()) // 数据源
                .engineConfig(buildEngineConfig()) // 引擎配置
                .produceConfig(buildProcessConfig()) // 处理配置
                .build();

        // 执行 screw，生成数据库文档
        new DocumentationExecute(config).execute();
    }

    /**
     * 创建数据源
     */
    private static DataSource buildDataSource() {
        // 创建 HikariConfig 配置类
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
        hikariConfig.setUsername(DB_USERNAME);
        hikariConfig.setPassword(DB_PASSWORD);
        hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
        // 创建数据源
        return new HikariDataSource(hikariConfig);
    }

    /**
     * 创建 screw 的引擎配置
     */
    private static EngineConfig buildEngineConfig() {
        return EngineConfig.builder()
                .fileOutputDir(FILE_OUTPUT_DIR) // 生成文件路径
                .openOutputDir(false) // 打开目录
                .fileType(FILE_OUTPUT_TYPE) // 文件类型
                .produceType(EngineTemplateType.freemarker) // 文件类型
                .fileName(DOC_FILE_NAME) // 自定义文件名称
                .build();
    }

    /**
     * 创建 screw 的处理配置，一般可忽略
     * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
     */
    private static ProcessConfig buildProcessConfig() {
        return ProcessConfig.builder()
                .designatedTableName(Collections.<String>emptyList())  // 根据名称指定表生成
                .designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
                .designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
                .ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
                .ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
                .ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
                .build();
    }

}

代码比较简单，胖友看看注释即可。

比较重要的变量，已经抽取成静态变量，胖友看着修改哈。

3.1.3 简单测试

执行 ScrewMain 程序，进行文档的生成。这里我们生成的是 HTML 文档，效果如下图所示：

HTML 文档

3.2 使用 Maven 插件的方式

创建 lab-70-db-doc-screw-02 示例项目，使用 screw 的 Maven 插件 的方式，生成文档。

示例示例

3.2.1 引入插件

在 pom.xml 文件中，引入 screw 的插件 screw-maven-plugin。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-02</artifactId>

    <build>
        <plugins>
            <plugin>
                <groupId>cn.smallbun.screw</groupId>
                <artifactId>screw-maven-plugin</artifactId>
                <version>1.0.5</version>
                <dependencies>
                    <!-- 数据库连接 -->
                    <dependency>
                        <groupId>com.zaxxer</groupId>
                        <artifactId>HikariCP</artifactId>
                        <version>3.4.5</version>
                    </dependency>
                    <dependency>
                        <groupId>mysql</groupId>
                        <artifactId>mysql-connector-java</artifactId>
                        <version>8.0.22</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <!-- 数据库相关配置 -->
                    <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                    <jdbcUrl>jdbc:mysql://400-infra.server.iocoder.cn:3306/mall_system</jdbcUrl>
                    <username>root</username>
                    <password>3WLiVUBEwTbvAfsh</password>
                    <!-- screw 配置 -->
                    <fileType>HTML</fileType>
                    <title>数据库文档</title> <!--标题-->
                    <fileName>测试文档名称</fileName> <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
                    <description>数据库文档生成</description> <!--描述-->
                    <version>${project.version}</version> <!--版本-->
                    <openOutputDir>false</openOutputDir> <!--打开文件输出目录-->
                    <produceType>freemarker</produceType> <!--生成模板-->
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

Maven 插件的配置项 比较少，胖友按需修改下 <configuration/> 即可。

3.2.2 简单测试

执行 screw-maven-plugin 插件，会在 doc 目录下生成文档。如下图所示：

执行 Maven 插件

4. 生成实体类

screw 的实现原理，是基于数据库中的表结构 ，生成对应的文档。

那么，是否可以自动生成 Java 实体类呢？答案是可以的，在 screw-extension 项目中，拓展提供了该功能。

这样，日常开发中，在我们完成数据库的建表之后，可以直接生成对应的 Java 实体类，避免枯燥的重复劳动。

下面，我们来快速入门下。创建 lab-70-db-doc-screw-03 示例项目，使用 screw 的 Java 代码 的方式，生成 Java 实体类。

示例示例

4.1 引入依赖

在 pom.xml 文件中，额外引入 screw 的依赖 screw-extension。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>lab-70-db-doc</artifactId>
        <groupId>cn.iocoder.springboot.labs</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-70-db-doc-screw-03</artifactId>

    <dependencies>
        <!-- screw 库，简洁好用的数据库表结构文档生成器 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-extension</artifactId>
            <version>1.0.5</version>
        </dependency>

        <!-- 数据库连接 -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.22</version>
        </dependency>
    </dependencies>

</project>

友情提示：由于 screw-extension 项目处于初步开发阶段，暂时未将该依赖推到 Maven 中央仓库，所以需要自己克隆项目，进行编译打包到本地。

4.2 ScrewMain

创建 ScrewMain 类，使用 screw 生成 Java 实体类。代码如下：

public class ScrewMain {

    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";

    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final String JAVA_CLASS_PACKAGE = "cn.iocoder.dataobject";

    public static void main(String[] args) {
        // 创建 screw 的配置
        PojoConfiguration config = PojoConfiguration.builder()
                .path(FILE_OUTPUT_DIR) // 生成 POJO 相关的目录
                .packageName(JAVA_CLASS_PACKAGE) // 包名
                .nameStrategy(new HumpNameStrategy()) // 包名策略
                .useLombok(false) // 是否使用 Lombok
                .dataSource(buildDataSource()) // 数据源
                .processConfig(buildProcessConfig()) // 处理配置
                .build();

        // 执行 screw，生成 POJO 实体类
        new PojoExecute(config).execute();
    }

    /**
     * 创建数据源
     */
    private static DataSource buildDataSource() {
        // 创建 HikariConfig 配置类
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
        hikariConfig.setUsername(DB_USERNAME);
        hikariConfig.setPassword(DB_PASSWORD);
        hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
        // 创建数据源
        return new HikariDataSource(hikariConfig);
    }

    /**
     * 创建 screw 的处理配置，一般可忽略
     * 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
     */
    private static ProcessConfig buildProcessConfig() {
        return ProcessConfig.builder()
                .designatedTableName(Collections.<String>emptyList())  // 根据名称指定表生成
                .designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
                .designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
                .ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
                .ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
                .ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
                .build();
    }

}

代码比较简单，胖友看看注释即可。不同于上面的快速入门，这里我们使用 PojoConfiguration 作为配置类，使用 PojoExecute 作为执行器。

比较重要的变量，已经抽取成静态变量，胖友看着修改哈。

如果您正在学习Spring Boot，推荐一个连载多年还在继续更新的免费教程：http://blog.didispace.com/spring-boot-learning-2x/

4.3 简单测试

执行 ScrewMain 程序，进行 Java 实体类的生成。效果如下图所示：

Java 实体类

生成的 Java 实体类的成员属性 还不太正确，需要等待作者进行下修复。

666. 彩蛋

至此，我们已经完成 screw 的学习，一起来简单总结下：

screw 支持生成数据库表结构文档 ，通过 Java 代码或者 Maven 插件的方式。
screw 支持生成 Java 实体类 ，通过 screw-extension 提供。

初略喵了下 screw 的代码，总体代码量在 5000+ 行，核心代码在 2000 行左右。项目分层干净，代码注释完成，胖友可以选择阅读了解下。这样，我们可以根据我们实际项目的需要，进行二次开发 。

往期推荐

被前公司辞退后，前领导打电话命令你给前同事解释代码，该怎么办？

国庆第一天：先换个头像，然后分享下国庆学习计划吧！

Spring Boot 实现扫码登录，这种方式太香了！！

这是什么神仙公司？居然公布离职员工信息，还给差评？

“80后的人，真的该退出IT行业了”，某IT公司领导言论惹争议！

技术交流群

最近有很多人问，有没有读者交流群，想知道怎么加入。加入方式很简单，有兴趣的同学，只需要点击下方卡片，回复“加群“，即可免费加入我们的高质量技术交流群！

点击阅读原文，送你免费Spring Boot教程！

: ， . Video Mini Program Like ，轻点两下取消赞 Wow ，轻点两下取消在看

《鱿鱼游戏2》今天下午四点开播，网友无心上班了，导演悄悄剧透

宾曰语云被法学教授投诉：严重侵权，“违法犯罪”！

当“上帝”变为“老天爷”

京东Plus的隐藏特权，很多会员都没领取，白交了会员费...

呼吁四川大学澄清：1998年1月，川大有多少个“姜涛与爱人程月玲”？

数据库界的Swagger：一键生成数据库文档！你不了解一下？

2. screw 简介

3. 快速入门

3.1 使用 Java 代码的方式

3.1.1 引入依赖

3.1.2 ScrewMain

3.1.3 简单测试

3.2 使用 Maven 插件的方式

3.2.1 引入插件

3.2.2 简单测试

4. 生成实体类

4.1 引入依赖

4.2 ScrewMain

4.3 简单测试

666. 彩蛋

您可能也对以下帖子感兴趣

《鱿鱼游戏2》今天下午四点开播，网友无心上班了，导演悄悄剧透

宾曰语云被法学教授投诉：严重侵权，“违法犯罪”！

当“上帝”变为“老天爷”

京东Plus的隐藏特权，很多会员都没领取，白交了会员费...

呼吁四川大学澄清：1998年1月，川大有多少个“姜涛与爱人程月玲”？

生成图片，分享到微信朋友圈

数据库界的Swagger：一键生成数据库文档！你不了解一下？

2. screw 简介

3. 快速入门

3.1 使用 Java 代码的方式

3.1.1 引入依赖

3.1.2 ScrewMain

3.1.3 简单测试

3.2 使用 Maven 插件的方式

3.2.1 引入插件

3.2.2 简单测试

4. 生成实体类

4.1 引入依赖

4.2 ScrewMain

4.3 简单测试

666. 彩蛋

您可能也对以下帖子感兴趣